home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / file.n < prev    next >
Encoding:
Text File  |  1994-12-17  |  5.1 KB  |  135 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) file.n 1.3 94/12/17 16:17:53
  9. '\" 
  10. .so man.macros
  11. .HS file tcl
  12. .BS
  13. '\" Note:  do not modify the .SH NAME line immediately below!
  14. .SH NAME
  15. file \- Manipulate file names and attributes
  16. .SH SYNOPSIS
  17. \fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?
  18. .BE
  19.  
  20. .SH DESCRIPTION
  21. .PP
  22. This command provides several operations on a file's name or attributes.
  23. \fIName\fR is the name of a file;
  24. if it starts with a tilde, then tilde substitution is done before
  25. executing the command (see the manual entry for \fBTcl_TildeSubst\fR
  26. for details).
  27. \fIOption\fR indicates what to do with the file name.  Any unique
  28. abbreviation for \fIoption\fR is acceptable.  The valid options are:
  29. .TP
  30. \fBfile \fBatime \fIname\fR
  31. Returns a decimal string giving the time at which file \fIname\fR
  32. was last accessed.  The time is measured in the standard POSIX
  33. fashion as seconds from a fixed starting time (often January 1, 1970).
  34. If the file doesn't exist or its access time cannot be queried then an
  35. error is generated.
  36. .TP
  37. \fBfile \fBdirname \fIname\fR
  38. Returns all of the characters in \fIname\fR up to but not including
  39. the last slash character.  If there are no slashes in \fIname\fR
  40. then returns ``.''.  If the last slash in \fIname\fR is its first
  41. character, then return ``/''.
  42. .TP
  43. \fBfile \fBexecutable \fIname\fR
  44. Returns \fB1\fR if file \fIname\fR is executable by
  45. the current user, \fB0\fR otherwise.
  46. .TP
  47. \fBfile \fBexists \fIname\fR
  48. Returns \fB1\fR if file \fIname\fR exists and the current user has
  49. search privileges for the directories leading to it, \fB0\fR otherwise.
  50. .TP
  51. \fBfile \fBextension \fIname\fR
  52. Returns all of the characters in \fIname\fR after and including the
  53. last dot in the last element of \fIname\fR.  If there is no dot in
  54. the last element of \fIname\fR then returns
  55. the empty string.
  56. .TP
  57. \fBfile \fBisdirectory \fIname\fR
  58. Returns \fB1\fR if file \fIname\fR is a directory,
  59. \fB0\fR otherwise.
  60. .TP
  61. \fBfile \fBisfile \fIname\fR
  62. Returns \fB1\fR if file \fIname\fR is a regular file,
  63. \fB0\fR otherwise.
  64. .TP
  65. \fBfile lstat \fIname varName\fR
  66. Same as \fBstat\fR option (see below) except uses the \fIlstat\fR
  67. kernel call instead of \fIstat\fR.  This means that if \fIname\fR
  68. refers to a symbolic link the information returned in \fIvarName\fR
  69. is for the link rather than the file it refers to.  On systems that
  70. don't support symbolic links this option behaves exactly the same
  71. as the \fBstat\fR option.
  72. .TP
  73. \fBfile \fBmtime \fIname\fR
  74. Returns a decimal string giving the time at which file \fIname\fR
  75. was last modified.  The time is measured in the standard POSIX
  76. fashion as seconds from a fixed starting time (often January 1, 1970).
  77. If the file doesn't exist or its modified time cannot be queried then an
  78. error is generated.
  79. .TP
  80. \fBfile \fBowned \fIname\fR
  81. Returns \fB1\fR if file \fIname\fR is owned by the current user,
  82. \fB0\fR otherwise.
  83. .TP
  84. \fBfile \fBreadable \fIname\fR
  85. Returns \fB1\fR if file \fIname\fR is readable by
  86. the current user, \fB0\fR otherwise.
  87. .TP
  88. \fBfile readlink \fIname\fR
  89. Returns the value of the symbolic link given by \fIname\fR (i.e. the
  90. name of the file it points to).  If
  91. \fIname\fR isn't a symbolic link or its value cannot be read, then
  92. an error is returned.  On systems that don't support symbolic links
  93. this option is undefined.
  94. .TP
  95. \fBfile \fBrootname \fIname\fR
  96. Returns all of the characters in \fIname\fR up to but not including
  97. the last ``.'' character in the name.  If \fIname\fR doesn't contain
  98. a dot, then returns \fIname\fR.
  99. .TP
  100. \fBfile \fBsize \fIname\fR
  101. Returns a decimal string giving the size of file \fIname\fR in bytes.
  102. If the file doesn't exist or its size cannot be queried then an
  103. error is generated.
  104. .TP
  105. \fBfile \fBstat  \fIname varName\fR
  106. Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the
  107. variable given by \fIvarName\fR to hold information returned from
  108. the kernel call.
  109. \fIVarName\fR is treated as an array variable,
  110. and the following elements of that variable are set: \fBatime\fR,
  111. \fBctime\fR, \fBdev\fR, \fBgid\fR, \fBino\fR, \fBmode\fR, \fBmtime\fR,
  112. \fBnlink\fR, \fBsize\fR, \fBtype\fR, \fBuid\fR.
  113. Each element except \fBtype\fR is a decimal string with the value of
  114. the corresponding field from the \fBstat\fR return structure; see the
  115. manual entry for \fBstat\fR for details on the meanings of the values.
  116. The \fBtype\fR element gives the type of the file in the same form
  117. returned by the command \fBfile type\fR.
  118. This command returns an empty string.
  119. .TP
  120. \fBfile \fBtail \fIname\fR
  121. Returns all of the characters in \fIname\fR after the last slash.
  122. If \fIname\fR contains no slashes then returns \fIname\fR.
  123. .TP
  124. \fBfile \fBtype \fIname\fR
  125. Returns a string giving the type of file \fIname\fR, which will be
  126. one of \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR,
  127. \fBblockSpecial\fR, \fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
  128. .TP
  129. \fBfile \fBwritable \fIname\fR
  130. Returns \fB1\fR if file \fIname\fR is writable by
  131. the current user, \fB0\fR otherwise.
  132.  
  133. .SH KEYWORDS
  134. attributes, directory, file, name, stat
  135.